﻿<!DOCTYPE HTML>
<html lang="zh">
<head>
<title>Map 对象 - 方法 &amp; 属性 | AutoHotkey v2</title>
<meta name="description" content="A Map object associates or maps one set of values, called keys, to another set of values." />
<meta name="ahk:equiv-v1" content="objects/Object.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>Map 对象</h1>
<pre class="NoIndent">class Map extends Object</pre>

<p><strong>Map(映射)</strong> 对象将一组称为 <em>键</em> 的值关联或 <em>映射</em> 到另一组值. 键及其映射到的值称为键-值对. 映射可以包含任意数量的键值对, 但是每个键必须是唯一的.</p>
<p>键可以是任何<a href="../Concepts.htm#numbers">整数</a>, <a href="../Objects.htm">对象</a>引用或以 null 结尾的<a href="../Concepts.htm#strings">字符串</a>. 字符串键的比较是区分大小写的, 而对象是通过引用/地址进行比较的. <a href="../Concepts.htm#numbers">浮点数</a>键被自动转换成字符串.</p>
<p>映射的最简单用法是通过隐式的 <a href="#__Item">__Item</a> 属性检索或设置键-值对, 只需在映射对象后面的方括号中写入键. 例如:</p>
<pre>clrs := Map()
clrs["Red"] := "ff0000"
clrs["Green"] := "00ff00"
clrs["Blue"] := "0000ff"
for clr in Array("Blue", "Green")
    MsgBox clrs[clr]
</pre>
<p>下面使用 "MapObj" 作为任何 Map 对象的占位符, 因为 "Map" 就是类本身.</p>
<p>除了从 <a href="Object.htm">Object</a> 继承的方法和属性外, Map 对象还具有以下预定义的方法和属性:</p>

<p><strong>静态方法:</strong></p>
<ul>
  <li><a href="#Call">Call</a></li>
</ul>
<p><strong>方法:</strong></p>
<ul>
  <li><a href="#Clear">Clear</a></li>
  <li><a href="#Clone">Clone</a></li>
  <li><a href="#Delete">Delete</a></li>
  <li><a href="#Get">Get</a></li>
  <li><a href="#Has">Has</a></li>
  <li><a href="#Set">Set</a></li>
  <li><a href="#__Enum">__Enum</a></li>
  <li><a href="#__New">__New</a></li>
</ul>
<p><strong>属性:</strong></p>
<ul>
  <li><a href="#Count">Count</a></li>
  <li><a href="#Capacity">Capacity</a></li>
  <li><a href="#CaseSense">CaseSense</a></li>
  <li><a href="#Default">Default</a></li>
  <li><a href="#__Item">__Item</a></li>
</ul>

<h2 id="StaticMethods">静态方法</h2>

<div class="methodShort" id="Call"><h2>Call</h2>
<p>创建一个 Map 并设置项目.</p>
<pre class="Syntax">MapObj := <span class="func">Map</span>(Key1, Value1, Key2, Value2, ...)</pre>
<p>这等同于使用用 <code>MapObj[Key] := Value</code> 来设置每个项目, 除了 <a href="#__Item">__Item</a> 没有被调用, 而且 <a href="#Capacity">Capacity</a> 会被自动调整以避免在一次调用中多次扩展.</p>
<p>参数由 <a href="#__New">__New</a> 定义.</p>
</div>

<h2 id="Methods">方法</h2>

<div class="methodShort" id="Clear"><h2>Clear</h2>
<p>从映射中删除所有键-值对.</p>
<pre class="Syntax">MapObj.<span class="func">Clear</span>()</pre>
</div>

<div class="methodShort" id="Clone"><h2>Clone</h2>
<p>返回对象的一个浅拷贝.</p>
<pre class="Syntax">Clone := MapObj.<span class="func">Clone</span>()</pre>
<p>所有键-值对都被复制到新映射. 对象 <em>引用</em> 被复制(就像普通的赋值一样), 而不是对象本身.</p>
<p>根据 <a href="Object.htm#Clone">Obj.Clone</a> 来复制自有的属性, 方法和基.</p>
</div>

<div class="methodShort" id="Delete"><h2>Delete</h2>
<p>从映射中删除键-值对.</p>
<pre class="Syntax">MapObj.<span class="func">Delete</span>(Key)</pre>
<dl>
  <dt>Key</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a>, <a href="../Objects.htm">对象</a>或<a href="../Concepts.htm#strings">字符串</a></p>
    <p>任意一个键. 如果映射不包含此键, 则抛出 <a href="Error.htm#KeyError">KeyError</a>.</p>
  </dd>
  <dt>返回值</dt>
  <dd><p>删除的值.</p></dd>
</dl>
</div>

<div class="methodShort" id="Get"><h2>Get</h2>
<p>返回键关联的值, 或者一个默认值.</p>
<pre class="Syntax">Value := MapObj.<span class="func">Get</span>(Key <span class="optional">, Default</span>)</pre>
<p>此方法执行以下操作:</p>
<ul>
  <li>返回与 <em>Key</em> 关联的值, 如果找到.</li>
  <li>如果 <em>Default</em> 参数的值, 如果指定.</li>
  <li>返回 <code>MapObj.Default</code> 的值, 如果定义.</li>
  <li>抛出 <a href="Error.htm#KeyError">KeyError</a>.</li>
</ul>
<p>当 <em>Default</em> 被省略时, 这等同于 <code>MapObj[Key]</code>, 除了没有调用 <a href="#__Item">__Item</a>.</p>
</div>

<div class="methodShort" id="Has"><h2>Has</h2>
<p>如果 <i>Key</i> 在映射中有关联的值, 则返回 true, 否则返回 false.</p>
<pre class="Syntax">MapObj.<span class="func">Has</span>(Key)</pre>
</div>

<div class="methodShort" id="Set"><h2>Set</h2>
<p>设置零个或多个项目.</p>
<pre class="Syntax">MapObj.<span class="func">Set</span>(<span class="optional">Key, Value, Key2, Value2, ...</span>)</pre>
<p>这相当于用 <code>MapObj[Key] := Value</code> 来设置每个项目, 除了 <a href="#__Item">__Item</a> 没有被调用和 <a href="#Capacity">Capacity</a> 会被自动调整, 以避免在一次调用中扩展多次.</p>
<p>返回 map 对象.</p>
</div>

<div class="methodShort" id="__Enum"><h2>__Enum</h2>
<p>枚举键-值对.</p>
<pre class="Syntax">For Key <span class="optional">, Value</span> in MapObj</pre>
<p>返回一个新的<a href="Enumerator.htm">枚举器</a>. 该方法通常不直接调用. 而是将映射对象被直接传递给 <a href="../commands/For.htm">for-loop</a>, 其调用一次 __Enum 然后循环的每次迭代都调用一次枚举器. 每次对枚举器的调用都会返回下一个键和/或值. for-loop 的变量对应于枚举器的参数, 它们是:</p>
<dl>
  <dt>Key</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a>, <a href="../Objects.htm">对象</a>或<a href="../Concepts.htm#strings">字符串</a></p>
    <p>键.</p>
  </dd>
  <dt>Value</dt>
  <dd>
    <p>值.</p>
  </dd>
</dl>
</div>

<h2 id="Properties">属性</h2>

<div class="methodShort" id="Count"><h2>Count</h2>
<p>检索映射中存在的键-值对的数量.</p>
<pre class="Syntax">Count := MapObj.<span class="func">Count</span></pre>
</div>

<div class="methodShort" id="Capacity"><h2>Capacity</h2>
<p>检索或设置映射的当前容量.</p>
<pre class="Syntax">MapObj.<span class="func">Capacity</span> := MaxItems</pre>
<pre class="Syntax">MaxItems := MapObj.<span class="func">Capacity</span></pre>
<dl>
	<dt>MaxItems</dt>
	<dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a></p>
    <p>在必须自动扩展前, 映射可以包含的最大键-值对数量. 如果设置的值小于当前键-值对数量, 则使用设置的值并释放未使用的空间.</p>
  </dd>
</dl>
</div>

<div class="methodShort" id="CaseSense"><h2>CaseSense</h2>
<p>检索或设置映射的大小写敏感性设置.</p>
<pre class="Syntax">MapObj.<span class="func">CaseSense</span> := Setting</pre>
<pre class="Syntax">Setting := MapObj.<span class="func">CaseSense</span></pre>
<dl>
	<dt>Setting</dt>
	<dd>
    <p>类型: <a href="../Concepts.htm#strings">字符串</a></p>
    <p>以下值之一:</p>
    <p><code>"On"</code>: 键查询区分大小写. 这是默认设置.</p>
    <p><code>"Off"</code>: 字母 A-Z 被视为与其小写字母相同.</p>
    <p><code>"Locale"</code>: 根据当前用户的区域设置规则, 键查询不区分大小写. 例如, 在大多数英语和西欧地区, 不仅将字母 A-Z 视为与其小写字母相同, 而且也将非 ASCII 字母如 &Auml; 和 &Uuml; 视为与其小写字母相同. 根据被比较字符串的性质, <em>Locale</em> 比 <em>Off</em> 慢 1 到 8 倍.</p>
    <p>在赋值时, 也可以使用字符串 <code>"1"</code> 和 <code>"0"</code>.</p>
  </dd>
</dl>
<p>如果 Map 不是空的, 尝试为该属性赋值将导致抛出异常.</p>
</div>

<div class="methodShort" id="Default"><h2>Default</h2>
<p>定义当没有找到键时返回的默认值.</p>
<pre class="Syntax">MapObj.<span class="func">Default</span> := Value</pre>
<p>默认情况下, 这个属性实际上并不存在, 但可以由脚本定义. 当脚本查询一个键没有找到时, map 会在抛出 <a href="Error.htm#KeyError">KeyError</a> 之前检查这个属性. 它可以通过任何正常的方式来实现, 包括<a href="Object.htm#DefineProp">动态属性</a>或<a href="../Objects.htm#Meta_Functions">元函数</a>, 但确定哪个键被查询到, 需要覆盖 <a href="#__Item">__Item</a> 或 <a href="#Get">Get</a> 来代替.</p>
</div>

<div class="methodShort" id="__Item"><h2>__Item</h2>
<p>检索或设置键-值对的值.</p>
<pre class="Syntax">Value := MapObj[Key]</pre>
<pre class="Syntax">MapObj[Key] := Value</pre>
<dl>
  <dt>Key</dt>
  <dd>
    <p>类型: <a href="../Concepts.htm#numbers">整数</a>, <a href="../Objects.htm">对象</a>或<a href="../Concepts.htm#strings">字符串</a></p>
    <p>检索值时, <em>Key</em> 必须是先前与另一个值相关联的唯一值. 如果 <em>Key</em> 在映射中没有关联的值, 则抛出 <a href="Error.htm#KeyError">KeyError</a>,  除非定义了 <a href="#Default">Default</a> 属性, 在这种情况下, 将返回其值.</p>
    <p>当赋值时, <em>Key</em> 可以是与 <em>Value</em> 相关联的任何值; 换句话说, <em>key</em> 用于以后访问 <em>Value</em>. <a href="../Concepts.htm#numbers">浮点数</a>键被自动转换成字符串.</p>
  </dd>
</dl>
<p></p>
<p>如上所示, 属性名 __Item 通常被省略, 但在覆盖属性时使用.</p>
</div>

<div class="methodShort" id="__New"><h2>__New</h2>
<p>设置项目. 等同于 <a href="#Set">Set</a>.</p>
<pre class="Syntax">MapObj.<span class="func">__New</span>(<span class="optional">Key, Value, Key2, Value2, ...</span>)</pre>
<p>这个方法是为了支持 <a href="#Call">Call</a> 而存在的, 并不打算直接调用. 请参阅<a href="../Objects.htm#Custom_NewDelete">构造和销毁</a>.</p>
</div>

</body>
</html>